home *** CD-ROM | disk | FTP | other *** search
/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 4.iso / findfuncs.README < prev    next >
Text File  |  1994-08-02  |  5KB  |  103 lines
  1.  
  2.                  ~4Dgifts/toolbox/README.findfuncs README
  3.  
  4.  
  5.       findfuncs:  is a shell-script providing search lookup and
  6.                   locate capabilities based on a multiple-keyword 
  7.                   list composed of library function-names for the
  8.           public, lib and src subtrees of the Toolbox.
  9.  
  10.  
  11.       this README explains the findfuncs script located in the top-level
  12.       directory of the Toolbox tree.  
  13.       
  14.       as a shell-script alternative to the sifttree GUI, findfuncs
  15.       enables identification of a program or programs implementing the 
  16.       list of library functions specified on the command line.  
  17.       
  18.       an hypothetical example wud be wanting to find all programs using
  19.       IRIS GL zbuffer and pixmode library functions:
  20.  
  21. < 212 ratmandu /4Dgifts/toolbox> findfuncs zbuffer pixmode
  22.         src/demos/REALITY/fastshadows/shad
  23.         src/demos/REALITY/fastshadows/shad.c
  24.         src/exampleCode/cap/src/cap
  25.         src/exampleCode/cap/tools/interp.c
  26.         src/exampleCode/stencil/gameOfLife
  27.  
  28.       shad, cap and gameOfLife are all ELF 32-bit MSB dynamic executable 
  29.       (not stripped) MIPS binary files.  notice findfuncs' ability to point
  30.       to the specific source file(s) where the matches occur as well as 
  31.       the binary.  in the case of gameOfLife, there is only one source file 
  32.       for which building an intermediate .o file was unnecessary.  the 
  33.       creation of the functions.INDEX file is based on all "ELF 32-bit MSB 
  34.       relocatable MIPS" (.o) files and "ELF 32-bit MSB dynamic executable
  35.       (not stripped) MIPS" (binary) files (the nomenclature here dervies 
  36.       from file(1)).  this is why the reference only points to the 
  37.       gameOfLife binary, not to the source file.
  38.  
  39. BUGS
  40.       for now, you must type the function(s) of interest with the proper
  41.       and exact UPPER and lower -case characters.  in v4.0 there is an 
  42.       anomoly with look(1), discovered by Dave Olson, wherein the -f flag 
  43.       ("Upper case letters compare equal to lower case.") does not work
  44.       as advertized.  as of the time we went to "press", we were not able 
  45.       to ascertain the reason for this.  if you are uncertain of the 
  46.       function name's proper UPPER/lower -case letters, run 
  47.       [f][e]grep -i functionname searchtools/functions.INDEX
  48.       this will list the function's exact spelling as you will need to 
  49.       specify in concert with findfuncs.
  50.  
  51.  
  52.  
  53.  
  54.  
  55.                Explanation of the Script-Logic behind findfuncs
  56.                ------------------------------------------------
  57.  
  58.       we include this explanation since the uses of this search-mechanism
  59.       are eminently generalizable beyond its implementation here.  since 
  60.       the Toolbox's raison d'etre is to provide tools--the more generic the 
  61.       better--we're extremely pleased to pass along this bit of "home-grown"
  62.       inspired work.
  63.  
  64.       findfuncs and the script ("getobjs") employed to generate the 
  65.       functions.INDEX file were created by that master (among MANY other 
  66.       things) of sed and elfdump, Dave Olson.  Dave generously donated his 
  67.       time to work up the two-levels of script-logic which provide a fast
  68.       and effective way of identifying program source code of interest 
  69.       anywhere in the "public," "lib" and "src" toolbox subtrees.  In 
  70.       essence, the mechanics employed to do this are:
  71.  
  72.     1.) with getobjs use find(1), sed(1), elfdump(1-SYSV), odump(1),
  73.         and /usr/lib/c++/c++filt, create the INDEX master "keyword 
  74.         list" file (renamed functions.INDEX for this application) 
  75.         associating all library functions invoked in object files 
  76.         with their equivalent source file as well as the program's 
  77.         binary, and then 
  78.  
  79.     2.) with findfuncs, a pointer to Dave's script named refjoin, 
  80.         use look(1), join(1) and sed(1) to sift the INDEX file for 
  81.         all mutually-inclusive occurences of the list of library 
  82.         functions and write to stdout the paths to where these 
  83.         functions reside.
  84.  
  85.       NOTE:  getobjs assumes it is using the elfdump from the 3.18 compilers
  86.          being released with IRIX 5.2.  in case you don't have IRIX 5.2
  87.          with the 3.18 compilers yet, and you want to use getobjs 
  88.          yerself, a copy of the newer elfdump is included in the 
  89.          searchtools directory.  you must use this version with getobjs
  90.          --any earlier version of elfdump than this will not work 
  91.          correctly with getobjs.
  92.  
  93.       FILES
  94.  
  95.       toolbox/findfuncs              top-level symlink to refjoin
  96.       toolbox/searchtools/functions.INDEX  index of all fxns w/their src/binary
  97.       toolbox/searchtools/refjoin    script for searching functions.INDEX
  98.       toolbox/searchtools/getobjs    script to build functions.INDEX
  99.       toolbox/searchtools/elfdump    3.18 compilers version needed by getobjs
  100.       toolbox/searchtools/look       used to find/print funcs fed to findfuncs
  101.       toolbox/searchtools/look.man   look man page
  102.       toolbox/searchtools/look.c     look source code
  103.